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Google JavaScript 风格 指南 


转载 一 下 Google JavaScript Style Guide, 文 章 不 但 指出 每 条 规范 ， 还 解释 了 为 什么 
这 样 写 的 原因 ， 同 时 给 出 了 对 与 错 的 实例 ， 写 得 非常 的 详细 ， 很 值 参 考 ， 正 在 考虑 
应 该 不 应 该 翻译 一 下 ， 然 后 借鉴 到 项 目 团队 中 去 ， 站 在 巨人 的 肩膀 上 会 看 得 更 远 。 
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JavaScript 是 一 种 客户 端 脚本 语言 , Google 的 许多 开源 工程 中 都 有 用 到 它 . 这 份 指 
南 列 出 了 编写 JavaScript 时 需要 遵守 的 规则 . 


JavaScript 语言 规范 


- 
AR EE 


又 里 
声明 变量 必须 加 上 var 关键 字 . 


Decision: 当 你 没有 写 var ,变量 就 会 暴露 在 全 局 上 下 文中 , 这 样 很 可 能 会 和 现 有 
变量 冲突 . 另外 , 如 果 没 有 加 上 , 很 难 明 确 该 变量 的 作用 域 是 什么 , 变量 也 很 可 能 像 在 
局 部 作用 域 中 , 很 轻易 地 泄漏 到 Document 或 者 Window 中 , 所 以 务必 用 var X 
声明 变量 . 


nu» uw. 
m 


常量 的 形式 如 : NAMES LIKE THIS ,即使 用 大 写字 符 , 并 用 下 划 线 分 隔 . 你 也 可 用 
Qconst 标记 来 指明 它 是 一 个 常量 . 但 请 永远 不 要 使 用 const 关键 词 . 


Decision: 
对 于 基本 类 型 的 常量 , 只 需 转 换 命 名 . 


Vas 
* The number of seconds in a minute. 
* @type {number} 
wh 

goog.example.SECONDS IN A MINUTE = 60; 


对 于 非 基 本 类 型 ,使 用 @const 标记 . 


VAN 
* The number of seconds in each of the given units. 
* Qtype (Object.<number>) 
* @const 
RP 
goog.example.SECONDS TABLE = { 
minute: 60, 
hour: 60 * 60, 
day: 60 * 60 * 24 
) 


是 常量 


这 标记 告诉 编译 器 它 是 常量 . 
至 于 关键 词 const ,因为 上 IE 不 能 识别 , 所 以 不 要 使 用 . 


分 号 


总 是 使 用 分 号 . 
如 果 仅 依靠 语句 间 的 隐 式 分 隔 , 有 时 会 很 麻烦 . 你 自己 更 能 清楚 哪里 是 语句 的 起 止 . 
而 且 有 些 情况 下 , 汤 掉 分 号 会 很 危险 : 


ie cbe 

MyClass.prototype.myMethod = function() { 
return 42; 

) // No semicolon here. 


(function() { 
// Some initialization code wrapped in a function to create a sc 


DO; 


var x = I 

bee de 

e 
) // No semicolon here. 
// 2N. Trying to do one thing on Internet Explorer and another on 
// I know you'd never write code like this, but throw me a bone. 
[normalVersion, ffVersion][isIE](); 


var THINGS TO EAT = [apples, oysters, sprayOnCheese] // No semico: 


// 3N. conditional execution a la bash 
-1 -- resultOfOperation() || die(); 





ix BEI AUR HE EE AS RE FE? 


1. 报 JavaScript 错误 一 例子 1 上 的 语句 会 解释 成 , 一 个 函数 带 一 匿名 函数 作为 参 
数 而 被 调用 , 返回 42 后 , 又 一 次 被 "调用 ” 这 就 导致 了 错误 . 
2. 例子 2 中 , 你 很 可 能 会 在 运行 时 遇 到 ‘no such property in undefined’ 错误 , Å 
是 代码 试图 这 样 x[ffversion][isIE]() 执行 . 
3. 3 resultofoperation() 返回 非 NaN 时 , 就 会 调用 die, 其 结果 也 会 赋 给 
THINGS TO EAT . 


为 什么 ? 


JavaScript 的 语句 以 分 号 作为 结束 符 , 除非 可 以 非常 准确 推断 某 结 束 位 置 才 会 省 略 
分 号 . 上 面 的 几 个 例子 产 出 错误 , 均 是 在 语句 中 声明 了 函数 /对 象 /数组 直接 量 , 但 闭 
括号 (个 或 了) 并 不 足以 表示 该 语 多 的 结束 . 在 JavaScript P, 只 有 当 语 和 句 后 的 下 一 个 
符号 是 后 级 或 括号 运算 符 时 , 才 会 认为 该 语句 的 结 


遗漏 分 号 有 时 会 出 现 很 奇怪 的 结果 ,所 以 确保 语句 以 分 号 结束 ， 
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4 
oh 


ah ES By BH 
可 以 使 用 


谋 套 函数 很 有 用 , 比如 ,减少 重复 代码 , 隐藏 帮助 函数 , 等 . 没什么 其 他 需要 注意 的 地 
方 , 随意 使 用 . 


RA KA S 
TREH APAA Å Å 
不 要 写成 : 


if (x) { 
function foo() {} 


} 


虽然 很 多 JS 引擎 都 支持 块 内 声明 函数 , 但 它 不 属于 ECMAScript 规范 ( 见 ECMA- 
262, 第 13 和 14 条 ). AMA SHAR OG IAA RARE, deb kx ECMAScript 
草案 相 违 背 . ECMAScript 只 允许 在 脚本 的 根 语句 或 函数 中 声明 遂 数 . 如 果 确 实 需 
J 建议 使 用 函数 表达 式 来 初始 化 变量 


if (x) { 


var foo = function() {} 


} 


ES 
HA 

"T 

你 在 写 一 个 比较 复杂 的 应 用 时 , 不 可 能 完全 避免 不 会 发 生 任 何 异 常 . 大 胆 去 用 吧 . 


自 定义 异常 
可 以 


ANKRET, 但 返回 的 错误 信息 比较 奇怪 , 也 不 易 读 . 虽然 可 以 将 含 错误 信息 的 
引用 对 象 或 者 可 能 产生 错误 的 完整 对 象 传 递 过 来 , 但 这 样 做 都 不 是 很 好 , 最 好 还 是 自 
定义 异常 类 , 其 实 这 些 基本 上 都 是 最 原始 的 异常 处 理 技巧 . 所 以 在 适当 的 时 候 使 用 自 
定义 异常 . 


标准 特性 
总 是 优 于 非 标准 特性 . 


最 大 化 可 移植 性 和 兼容 性 , 尽量 使 用 标准 方法 而 不 是 用 非 标准 方法 , (比如 , 优先 
用 string. charAt(3) 而 不 用 string[3] ,通过 DOM 原生 函数 访问 元 素 , 而 不 
是 使 用 应 用 封装 好 的 快速 接口 . 


封装 基本 类 型 
不 要 
没有 任何 理由 去 封装 基本 类 型 , 另外 还 存在 一 些 风险 : 


var x = new Boolean(false); 
if (x) { 

alert('hi'); // Shows "hi". 
j 


除非 明确 用 于 类 型 转换 , 其 他 情况 请 千 万 不 要 这 样 做 ! 


var x = Boolean(0); 
if (x) { 
alert('hi'); // This will never be alerted. 


typeof Boolean(0) == 'boolean'; 
typeof new Boolean(0) == 'object'; 


有 时 用 作 number , string X boolean 时 , 类 型 的 转换 会 非常 实用 . 


多 级 原型 结构 

不 是 首选 

多 级 原型 结构 是 指 JavaScript 中 的 继承 关系 . 当 你 自 定 义 一 个 D 类 , 且 把 B 类 作为 其 
原型 , 那么 这 就 获得 了 一 个 多 级 原型 结构 . 这 些 原 型 结构 会 变 得 越 来 越 复 杂 ! 
使 用 the Closure 库 中 的 goog.inherits() 或 其 他 类 似 的 用 于 继承 的 函数 , 会 是 
更 好 的 选择 . 


function D() { 
goog.base(this) 
) 
goog.inherits(D, B); 
D.prototype.method = function() I 


m 


方法 定义 
Foo.prototype.bar = function() { ... }; 


有 很 多 方法 可 以 给 构造 器 添加 方法 或 成 员 , 我 们 更 倾向 于 使 用 如 下 的 形式 : 


Foo.prototype.bar = function() { 
ER rS SE 
H 


Me 

可 以 , 但 小 心 使 用 . 

闭 包 也 许 是 JS 中 最 有 用 的 特性 了 . 

有 一 份 比较 好 的 介绍 闭 包 原理 的 文档 . 

有 一 点 需要 牢记 , 闭 包 保留 了 一 个 指向 它 封 闭 作 用 域 的 指针 , 所 以 , 在 给 DOM AR 
附加 闭 包 时 , 很 可 能 会 产生 循环 引用 , 进一步 导致 内 存 泄 漏 . 比如 下 面 的 代码 : 


function foo(element, a, b) ( 
element.onclick = function() ( /* uses a and b */ Y; 


j 


ix €. 即使 没有 使 用 element , 闭 包 也 保留 了 element, a 和 b 的 引用 ,. 由 
于 element 也 保留 了 对 闭 包 的 引用 , 这 就 产生 了 循环 引用 , 这 就 不 能 被 GC 回收 . 


这 种 情况 下 , 可 将 代码 重 构 为 : 


function foo(element, a, b) I 
element.onclick - bar(a, b); 


j 


function bar(a, b) ( 
return function() ( /* uses a and b */ } 


j 


eval() 


只 用 于 解析 序列 化 串 (如 : 解析 RPC 响应 ) 
eval() 会 让 程序 执行 的 比较 混乱 , 当 eval() 里 面包 含 用 户 输入 的 话 就 更 加 危 


me. 


可 以 用 其 他 更 佳 的 , 更 清晰 , 更 安全 的 方式 写 你 的 代码 , 所 以 一 般 情况 下 请 不 要 使 用 
eval(). 


当 碰 到 一 些 需要 解析 序列 化 串 的 情况 下 (如 , 计算 RPC 响应 ), 使 用 eval 很 容易 实 
现 . 


解析 序列 化 串 是 指 将 字 节 流转 换 成 内 存 中 的 数据 结构 . 比如 , 你 可 能 会 将 一 个 对 象 输 
出 成 文件 形式 : 


users = [ 
{ 
name: 'Eric', 
id: 37824, 
email: 'jellyvoreQmyway.com' 
i 
{ 


name: 'xtof', 

id: 31337, 

email: 'b4d455h4x0r@google.com' 
ty 


ip 


很 简单 地 调用 eval 后 , 把 表示 成 文件 的 数据 读 取 回 内 存 中 . 


类 似 的 ，eval() 对 RPC 响应 值 进行 解码 . 例如 , 你 在 使 用 XMLHttpRequest 发 
出 一 个 RPC 请 求 后 , 通过 eval () 将 服务 端的 响应 文本 转 成 JavaScript 对 象 : 


var userOnline = false; 
var user - 'nusrat'; 
var xmlhttp = new XMLHttpRequest(); 
xmlhttp.open('GET', 'http://chat.google.com/isUserOnline?user=' + ı 
xmlhttp.send(''); 
// Server returns: 
// userOnline = true; 
if (xmlhttp.status -- 200) ( 
eval(xmlhttp.responseText); 


// userOnline is now true. 








with() {} 


不 要 使 用 


使 用 with 让 你 的 代码 在 语义 上 变 得 不 清晰 . AA with 的 对 象 , 可 能 会 与 局 部 
变量 产生 冲突 , 从 而 改变 你 程序 原本 的 用 义 . 


下 面 的 代码 是 干 嘛 的 ? 


with (foo) 1 
var x = 3; 
return X; 


j 


答案 : 任何 事 . 局 部 变量 x 可 能 被 foo 的 属性 覆盖 , 当 它 定义 一 个 setter 时 , 在 
赋值 3 后 会 执行 很 多 其 他 代码 . 


所 以 不 要 使 用 with 语句 . 


this 
仅 在 对 象 构造 器 , 方法, 闭 包 中 使 用 . 


this 的 语义 很 特别 . 有 时 它 引用 一 个 全 局 对 象 (大 多 数 a 调用 者 的 作用 域 
eval Et), DOM 树 中 的 节点 (添加 事件 处 理 函 数 时 ), 新 创建 的 对 象 (使 用 一 个 
构造 器 ), 或 者 其 他 对 象 (如 果 函 数 被 call() 或 apply() ). 


使 用 时 很 容易 出 错 , 所 以 只 有 在 下 面 两 个 情况 时 才能 使 用 : 


e 在 构造 器 中 
e 对 象 的 方法 (包括 创建 的 闭 包 ) 中 


for-in #4 4% 


只 用 于 object/map/hash 的 遍历 


对 Array 用 for-in 循环 有 时 会 出 错 . 因为 它 并 不 是 从 0 到 length - 1 
进行 遍历 , 而 是 所 有 出 现在 对 象 及 其 原型 链 的 键 值 . 下 面 就 是 一 些 失败 的 使 用 案例 : 


function printArray(arr) ( 
for (var key in arr) { 
print(arr[key]); 


j 


printArray([0,1,2,3]); // This works. 


var a - new Array(10); 
printArray(a); // This is wrong. 


a = document.getElementsByTagName( '*'); 
printArray(a); // This is wrong. 


a = [0,1,2,3]; 
a.buhu = 'wine'; 
printArray(a); // This is wrong again. 


a - new Array; 
a[3] - 3; 
printArray(a); // This is wrong again. 


而 遍历 数组 通常 用 最 普通 的 for 循环 . 


function printArray(arr) ( 
var 1 = arr.length; 
for (var i = 0; i < 1; i++) { 
print(arr[i]); 


关联 数组 


永远 不 要 使 用 Array 作为 map/hash/associative 数组 . 


数组 中 不 允许 使 用 非 整 型 作为 索引 值 , 所 以 也 就 不 允许 用 关联 数组 . 而 取代 它 使 用 
Object 来 表示 map/hash 对 象 . 


Array 仅仅 是 扩展 自 Object (类 似 于 其 他 JS 中 的 对 象 , RR Date, 
RegExp 和 String ) 一 样 来 使 用 . 


GÅTT $ 
不 要 使 用 
不 要 这 样 写 长 字符 串 : 


var myString = 'A rather long string of English text, an error mes: 
actually that just keeps going and going -- an err« 
message to make the Energizer bunny blush (right tl 
those Schwarzenegger shades)! Where was I? Oh yes, 
you\'ve got an error and all the extraneous whites; 
just gravy. Have a nice day.'; 


p ————————————ásá 


在 编译 时 , 不 能 忽略 行 起 始 位 置 的 空白 字符 ; 只 后 的 空白 字符 会 产生 奇怪 的 错误 ; 虽 
然 大 多 数 脚本 引擎 支持 这 种 写法 , 但 它 不 是 ECMAScript 的 标准 规范 . 





Array 和 Object 直接 量 


使 用 


使 用 Array 和 Object 语法 , 而 不 使 用 Array 和 Object 构造 器 . 


iz 


使 用 Array 构造 器 很 容易 因为 传 参 不 恰当 导致 错误 . 


i E 


// Length is 3. 
var al = new Array(x1, x2, x3); 


// Length is 2. 
var a2 = new Array(x1, x2); 


// If x1 is a number and it is a natural number the length will be 
// If x1 is a number but not a natural number this will throw an e 
// Otherwise the array will have one element with x1 as its value. 
var a3 - new Array(x1); 


// Length is O0. 
var a4 - new Array(); 





如 果 传 入 一 个 参数 而 不 是 2 个 参数 , 数组 的 长 度 很 有 可 能 就 不 是 你 期 望 的 数值 了 . 


为 


RK; 


了 避免 这 些 歧义 ， 我 们 应 该 使 用 更 多 读 的 直接 量 来 声明 . 


Var = [x1, x2, x3]; 
var = [x1, x2]; 
var ss = [x1]; 

var a4 = []; 


然 Object 构造 器 没有 上 述 类 似 的 问题 , 但 鉴于 可 读 性 和 一 致 性 考虑 , 最 好 还 是 在 


字面 上 更 清 晰 地 指明 . 


var o = new Object(); 


var o2 - new Object(); 
02.a = 0; 
02.b = 1; 
02-0 27 


o2['strange key'] = 3; 


var 02 = { 


a: 0, 
D 
GE 2 


"strange key': 3 
3 


修改 内 置 对 象 的 原型 


不 要 


千 万 不 要 修改 内 置 对 象 , 如 Object.prototype 和 Array.prototype 的 原型 . 
而 修改 内 置 对 象 , 如 Function.prototype 的 原型 , 虽然 少 危 险些 , 但 仍 会 导致 调 
试 时 的 诡异 现象. 


所 以 也 要 避免 修改 其 原型 


IE 下 的 条 件 注释 
不 要 使 用 
不 要 这 样子 写 ; 


var f = function () I 
/*@cc_on if (@ jscript) { return 2* @*/ 3; /*@ } @*/ 
7; 


条 件 注释 妨碍 自动 化 工具 的 执行 , 因为 在 运行 时 , 它们 会 改变 JavaScript 语法 树 . 


JavaScript 编码 风格 


$ 


名 


通常 ,使 用 functionNamesLikeThis , variableNamesLikeThis , 
ClassNamesLikeThis , EnumNamesLikeThis , methodNamesLikeThis , fe 
SYMBOLIC CONSTANTS LIKE THIS. 


展开 见 细节 . 


属性 和 方法 


e 文件 或 类 中 的 私有 属性 , 变量 和 方法 名 应 该 以 下 划 线 “ ”开头 . 
e 保护 属性 , 变量 和 方法 名 不 需要 下 划 线 开头 , 和 公共 变量 名 一 样 . 


更 多 有 关 私有 和 保护 的 信息 见 ,visibility. 


方法 和 函数 参数 
可 选 参 数 以 opt AK. 


函数 的 参数 个 数 不 国定 时 , 应 该 添加 最 后 一 个 参数 var args 为 参数 的 个 数 . 你 也 
可 以 不 设置 var_args 而 取代 使 用 arguments . 


可 选 和 可 变 参 数 应 该 在 Qparam 标记 中 说 明 清 楚 . 虽然 这 两 个 规定 对 编译 器 没有 任 
何 影响 , 但 还 是 请 尽量 遵守 


Getters 和 Setters 

Getters 和 setters 并 不 是 必要 的 . 但 只 要 使 用 它们 了 , 就 请 将 getters 命名 成 
getFoo() 形式 , 将 setters 命名 成 setFoo(value) 形式 . (对 于 布尔 类 型 的 

getters, 使 用 isFoo() 也 可 .) 

命名 空间 

JavaScript 不 支持 包 和 命名 空间 . 


不 容易 发 现 和 调试 全 局 命名 的 冲突 , 多 个 系统 集成 时 还 可 能 因为 命名 冲突 导致 很 严 
重 的 问题 . 


为 了 提高 JavaScript 代码 复 用 率 , 我 们 遵循 下 面 的 约定 以 避免 冲突 . 
为 全 局 代码 使 用 命名 空间 


在 全 局 作用 域 上 , 使 用 一 个 唯一 的 , 与 工程 / 库 相 关 的 名 字 作 为 前 组 标识 . 比如 , 你 的 
工程 是 “Project Sloth”, 那么 命名 空间 前 组 可取 为 sloth.* . 


var sloth = {}; 


sloth.sleep = function() { 


å 


许多 JavaScript Æ, 包括 the Closure LibraryandDojo toolkit 为 你 提供 了 声明 你 自己 
的 命名 空间 的 函数 . 比如 : 


goog.provide('sloth'); 
sloth.sleep = function() { 


no 


明确 命名 空间 所 有 权 


当选 择 了 一 个 子 命名 空间 , 请 确保 父 命名 空间 的 负责 人 知道 你 在 用 哪个 子 命名 空间 ， 
比如 说 , 你 为 工程 ‘sloths’ 创建 一 一 个 hats 子 命名 空 ia), 那 确保 Sloth 团队 人 员 知道 你 
在 使 用 sloth.hats 


外 部 代码 和 内 部 代码 使 用 不 同 的 命名 空间 


“外 部 代码 ” 是 指 来 自 于 你 代码 体系 的 外 部 , 可 以 独立 编译 . 内 外 部 命名 应 该 严格 保持 
独立 . 


os Ss foo.hats. J 你 自己 的 代码 不 能 
在 foo.hats.* 下 命名 ， BRA TQ E RA 


foo.require('foo.hats'); 


YEE 
* WRONG -- Do NOT do this. 
* @constructor 
* Qextend {foo.hats.RoundHat } 
iy 
foo.hats.BowlerHat = function() { 


HH 


果 你 需要 在 外 部 命名 空间 中 定义 新 的 API, 那么 你 应 该 直接 导出 一 份 外 部 库 , 然后 
在 这 份 代码 中 修改 . 


在 你 的 内 部 代码 中 , 应 该 通过 他 们 的 内 部 名 字 来 调用 内 部 APL, 这 样 保 持 一 致 性 可 让 
编译 器 更 好 的 优化 你 的 代码 ， 


foo.provide('googleyhats.BowlerHat'); 
foo.require('foo.hats'); 


Jf rotta 
* (constructor 
* Qextend {foo.hats.RoundHat } 
DU 
googleyhats.BowlerHat = function() (1 


» 


goog.exportSymbol('foo.hats.BowlerHat', googleyhats.BowlerHat); 


重 命名 那些 名 字 很 长 的 变量 , 提高 可 读 性 
主要 是 为 了 提高 可 读 性 . 局 部 空间 中 的 变量 别名 只 需要 取 原 名 字 的 最 后 部 分 . 


VE 
* @constructor 
us 
some.long.namespace.MyClass = function() { 


H 


Jf otia 
* (param {some.long.namespace.MyClass} a 
SÅ 
some. long .namespace.MyClass.staticHelper = function(a) { 


- 


myapp.main = function() I 
var MyClass - some.long.namespace.MyClass; 
var staticHelper - some.long.namespace.MyClass.staticHelper; 
staticHelper(new MyClass()); 


) 


不 要 对 命名 空间 创建 别名 . 


myapp.main = function() { 
var namespace - some.long.namespace; 
namespace.MyClass.staticHelper(new namespace.MyClass()); 


除非 是 枚 举 类 型 ,不然 不 要 访问 别名 变量 的 属性 . 


/** @enum (string) */ 
some.long.namespace.Fruit - ( 
APPLE: 'a", 
BANANA: 'b' 


>; 


myapp.main = function() { 
var Fruit - some.long.namespace.Fruit; 
switch (fruit) { 
case Fruit.APPLE: 


case Fruit.BANANA: 


) 
}; 


myapp.main = function() { 

var MyClass = some.long.namespace.MyClass; 
MyClass.staticHelper(null); 

3 


不 要 在 全 局 范围 内 创建 别名 , 而 仅 在 函数 块 作 用 域 中 使 用 . 


文件 名 


文件 名 应 该 使 用 小 写字 符 , 以 避免 在 有 些 系统 平台 上 不 识别 大 小 写 的 命名 方式 . 文件 
名 以 .js 结尾 , 不 要 包含 除 - 和 外 的 标点 符号 (使 用 - RE). 


Å x L toString() 方法 
应 该 总 是 成 功 调用 且 不 要 抛 异 常 . 


可 自 定义 tostring() 方法 , 但 确保 你 的 实现 方法 满足 : (1) 总 是 成 功 (2) 没有 其 他 
负面 影响 . 


如 果 不 满足 这 两 个 条 件 , 那么 可 能 会 导致 严重 的 问题 , 比如 , 如 果 toString() 调 
用 了 包含 assert MAX, assert 输出 导致 失败 的 对 象 , 这 在 tostring() 
也 会 被 调用 . 


KE iR d 361v, 


"T 
没 必要 在 每 次 声明 变量 时 就 将 其 初始 化 . 


明确 作用 域 


任何 时 候 都 需要 


任何 时 候 都 要 明确 作用 域 — 提高 可 移植 性 和 清晰 度 . 例如 , 不 要 依赖 于 作用 域 链 中 的 
window £. 


可 能 在 其 他 应 用 中 , 你 函数 中 的 window 不 是 指 之 前 的 那个 窗口 对 象 


代码 格式 化 
展开 见 详 细 描 述 . 
主要 依照 C++ 格式 规范 ( 中 文 版 ), 针对 JavaScript, 还 有 下 面 一 些 附加 说 明 . 
大 括号 
分 号 会 被 隐 式 插入 到 代码 中 , 所 以 你 务必 在 同一 行 上 插入 大 括号 . 例如 : 
if (something) { 
Ju ces 


) else 
drops 


) 
数组 和 对 象 的 初始 化 
如 果 初 始 值 不 是 很 长 , 就 保持 写 在 单行 上 : 


[1, 2, 3]; // No space after [ or before |. 
(a: 1, b: 2, c: 3); // No space after ( or before }. 


var arr 
var obj 


// Object initializer. 
var inset = ( 

top: 10, 

right: 20, 

bottom: 15, 

left: 12 


HH 


// Array initializer. 

this.rows = [ 
'"Slartibartfast" <fjordmaster@magrathea.com>', 
'"Zaphod Beeblebrox" <theprez@universe.gov>', 
' "Ford Prefect" <ford@theguide.com>', 
""Arthur Dent" <has.no.tea@gmail.com>', 
'"Marvin the Paranoid Android" <marv@googlemail.com>', 
'the.miceQmagrathea.com' 


]: 


// Used in a method call. 
goog.dom.createDom(goog.dom.TagName.DIV, ( 
id: 'foo', 
className: 'some-css-class', 
style: 'display:none' 
}, 'Hello, world!'); 


比较 长 的 标识 符 或 者 数值 , 不 要 为 了 让 代码 好 看 些 而 手工 对 齐 . 
如 : 
CORRECT Object.prototype = I 
a: 0, 
pde 


lengthyName: 2 
3 


不 要 这 样 做 : 


WRONG Object.prototype = I 


a Sn. 
b Sq 
lengthyName: 2 


hE AL 


尽量 让 函数 参数 在 同一 行 上 . 


如 果 一 行 超过 80 FH, 每 个 参数 独占 一 行 , 并 以 4 个 空格 缩 进 , 或 者 与 括号 对 齐 ， 
提高 可 读 性 . 尽 可 能 不 要 让 每 行 超过 80 个 字符 . 比如 下 面 这 样 : 


// Four-space, wrap at 80\. Works with very long function names, : 
// renaming without reindenting, low on space. 
g009.f00.bar .doThingThatIsVeryDifficultToExplain = function( 
veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo, 
tableModelEventHandlerProxy, artichokeDescriptorAdapterIterato! 
// 


jee 


// Four-space, one argument per line. Works with long function nar 

// survives renaming, and emphasizes each argument. 

goog. foo.bar.doThingThatIsVeryDifficultToExplain = function( 
veryDescriptiveArgumentNumberOne, 
veryDescriptiveArgumentTwo, 
tableModelEventHandlerProxy, 
artichokeDescriptorAdapterIterator) ( 

// 


iz 


// Parenthesis-aligned indentation, wrap at 80N. Visually groups : 
// low on space. 
function foo(veryDescriptiveArgumentNumberOne, veryDescriptiveArgur 
tableModelEventHandlerProxy, artichokeDescriptorAdapte 
// 


j 


// Parenthesis-aligned, one argument per line. Visually groups anc 

// emphasizes each individual argument. 

function bar(veryDescriptiveArgumentNumberOne, 
veryDescriptiveArgumentTwo, 
tableModelEventHandlerProxy, 
artichokeDescriptorAdapterIterator) { 





传递 匿名 函数 


如 果 参 数 中 有 匿名 函数 ， 函数 体 从 调用 该 函数 的 左边 开始 缩 进 2 个 空格 ， Vires 
function 这 个 关键 字 开始 . RILESH BE Ja Fy i (不 要 增加 很 多 没 必要 的 缩 进 让 函 
数 体 显示 在 屏幕 的 右 侧 ). 


var names = items.map(function(item) ( 
return item.name; 


T): 


prefix.something.reallyLongFunctionName('whatever', function(a1, a: 
if (a1.equals(a2)) { 
someOtherLongFunctionName(a1); 


) else { 
andNowForSomethingCompletelyDifferent(a2.parrot); 








更 多 的 缩 进 


事实 上 , 除了 初始 化 数组 和 对 象 , 和 传递 匿名 函数 外 , 所 有 被 拆 开 的 多 行文 本 要 么 选 
择 与 之 前 的 表达 式 左 对 齐 , 要 么 以 4 个 (而 不 是 2 个 ) 空格 作为 一 缩 进 层 次 . 


someWonderfulHtml = '' + 
getEvenMoreHtml(someReallyInterestingValues, mc 


evenMoreParams, ‘a duck', true, 
slightlyMoreMonkeys(Oxfff)) + 


tr. 
, 


thisIsAVeryLongVariableName - 
herelIsAnEvenLongerOtherFunctionNameThatWillNotFitOnPrevLine(); 


thisIsAVeryLongVariableName = 'expressionPartOne' + someMethodThat: 
thisIsAnEvenLongerOtherFunctionNameThatCannotBeIndentedMore(); 


someValue - this.foo( 
shortArg, 
"Some really long string arg - this is a pretty common case, ac 
shorty2, 
this.bar()); 


if (searchableCollection(allYourStuff).contains(theStuffYouWant) & 
'ambientNotification.isActive() && (client.isAmbientSupported(: 
client.alwaysTryAmbientAnyv 


ambientNotification.activate(); 





doSomethingTo(x); 
doSomethingElseTo(x); 
andThen(x); 


nowDoSomethingWith(y); 


andNowWith(z); 


二 元 和 三 元 操作 符 


操作 符 始终 跟随 着 前 行 , 这 样 就 不 用 顾虑 分 号 的 隐 式 插入 问题 . 如 果 一 行 实在 放 不 下 ， 
还 是 按照 上 述 的 缩 进 风格 来 换行 . 


var x =a?b: c; // All on one line if it will fit. 


// Indentation +4 is OK. 
var y = a ? 
longButSimpleOperandB : longButSimpleOperandC; 


// Indenting to the line position of the first operand is also OK. 
varz-a? 

moreComplicatedB : 

moreComplicatedC; 


[| —$——S me ege... NJÅ 


括号 


只 在 需要 的 时 候 使 用 
不 要 滥用 括号 , 只 在 必要 的 时 候 使 用 它 . 


对 于 一 元 操作 符 ( 如 delete , typeof 和 void ), 或 是 在 茶 些 关 键 词 (如 
return , throw , case , new ) 之 后 , 不 要 使 用 括号 . 


字符 串 

HTC 

单 引号 () 优 于 双 引 号 (9). 

当 你 创建 一 个 包含 HTML 代码 的 字符 串 时 就 知道 它 的 好 处 了 . 


可 见 性 (私有 域 和 保护 域 ) 


推荐 使 用 JSDoc 中 的 两 个 标记 : @private 和 @protected 


JSDoc 的 两 个 标记 Qprivate 和 @protected 用 来 指明 类 , BR, 属性 的 可 见 性 
X. 


标记 为 QGprivate 的 全 局 变量 和 函数 , 表示 它们 只 能 在 当前 文件 中 访问 . 


标记 为 Qprivate 的 构造 器 , 表示 该 类 只 能 在 当前 文件 或 是 其 静 vds 成 员 中 实 
BAG: 私有 构造 器 的 公共 静态 属性 在 当前 文件 的 任何 地 方 都 可 访问 , 38 
instanceof 操作 符 也 可 


永远 不 要 为 全 局 变量 , BK, 构造 器 加 Qprotected 标记 . 


// File 1. 
// AA PrivateClass and AA init are accessible because they are g: 
// and in the same file. 


JØRGEN 
* Qprivate 
* (constructor 
så 
AA PrivateClass = function() { 
u 
/** Qprivate */ 


function AA init () I 
return new AA PrivateClass (); 


) 
AA init (); 
二 0 0 =- 


标记 为 Qprivate 的 属性 , 在 当前 文件 中 可 访问 它 ; 如 果 是 类 属性 私有 “拥有 ”该 属 
性 的 类 的 所 有 静态 /普通 成 员 也 可 访问 ， 但 它们 不 能 被 不 同文 件 中 的 子 类 访问 或 覆盖 . 


标记 为 Qprotected 的 属性 ,在 当前 文件 中 可 访问 它 , 如 果 是 类 属性 保护 , MAM 
有 "该 属性 的 类 及 其 子 类 中 的 所 有 静态 /普通 成 员 也 可 访问 . 





注意 : KA Ct, Java 中 的 私有 和 保护 不 同 , 它们 是 在 当前 文件 中 , 检查 FLA 
问 私有 /保护 属性 的 权限 , 有 权限 即 可 访问 , 而 不 是 只 能 在 同一 个 类 i. 上 .而 


C++ PAYA A BER AIRFARES. 


(C++/Java 中 的 私有 /保护 是 指 作用 域 上 的 可 访问 性 , 在 可 访问 性 上 的 限制 . JS 中 是 
在 限制 在 作用 域 上 . PS: 可 见 性 是 与 作用 域 对 应 ) 


// File 1. 


/** @constructor */ 
AA PublicClass = function() { 


>; 


/** Qprivate */ 
AA PublicClass.staticPrivateProp = 1; 


/** @private */ 
AA PublicClass.prototype.privateProp = 2; 


/** @protected */ 
AA PublicClass.staticProtectedProp - 31; 


/** @protected */ 
AA PublicClass.prototype.protectedProp - 4; 


// File 2. 


J/ etta 
* @return {number} The number of ducks we've arranged in a row. 
n 
AA PublicClass.prototype.method = function() I 
// Legal accesses of these two properties. 
return this.privateProp + AA PublicClass.staticPrivateProp ; 


yi 
// File 3. 


Ce 
* (constructor 
* Qextends (AA PublicClass) 
a 
AA_SubClass = function() { 
// Legal access of a protected static property. 
AA_PublicClass.staticProtectedProp = this.method(); 
}; 
goog.inherits(AA SubClass, AA PublicClass); 


yf otia 
* @return {number} The number of ducks we've arranged in a row. 
ind 
AA SubClass.prototype.method - function() ( 
// Legal access of a protected instance property. 
return this.protectedProp; 


H 


JavaScript 类 型 


强烈 建议 你 去 使 用 编译 器 . 


如 果 使 用 JSDoc, 那么 尽量 具体 地 , 准确 地 根据 它 的 规则 来 书写 类 型 说 明 . 目前 支持 
两 种 JS2 和 JS1.x 类 型 规范 . 


JavaScript 类 型 语言 


` 
一 > 一 


JS2 提议 中 包含 了 一 种 描述 JavaScript 类 型 的 规范 语法 , 这 里 我 们 在 JSDoc 中 采用 
其 来 描述 函数 参数 和 返回 值 的 类 型 . 


JSDoc 的 类 型 语言 , 按照 JS2 规范 , 也 进行 了 适当 改变 , 但 编译 器 仍然 支持 昌 语 法 . 


名 称 


记录 类 型 


型 


语法 


{boolean} , (Window) , {goog.ui.Menu} 


{Array.<string>} FA PAHA. 
{Object.<string, number») 键 为 字符 串 , 值 为 
整数 的 对 象 类 型 . 


{(number&#124;boolean)} 


{{myNum: number, myObject}} 由 现 有 类 型 组 成 
的 类 型 . 


(number) 一 个 整 型 数 或 者 为 NULL 


{!Object} 一 个 对 象 , 但 绝 不 会 是 null 4a. 


一 个 整数 或 者 布尔 值 . 


通 
参数 化 类 型 ， 
GRP a4 
列 ? 类 型 参数 ' 
Java 中 的 泛 


KIT HAT å 
型 ,也 可 能 是 


表示 包含 指 % 
类 型 的 值 . 这 
myNum 为 
RAY myob: 
任意 类 型 . 注 
为 类 型 语法 
比如 ， 

Array.«(l 
表示 一 具有 
属性 的 _Arr 


表示 一 个 值 # 
类 型 或 者 m 
认 , 每 个 对 象 
空 的 . 注意 : i 
不 可 为 空 . 

VE — MA 
且 肯 定 不 是 1 
情况 下 , 所 有 
(boolean, nu 


函数 的 tk 


函数 可 选 
参数 (使 
用 
Qparam 
标记 ) 


所 有 类 型 


{function(string, boolean)} 具有 两 个 参数 ( 
string 和 boolean) 的 部 数 类 型 , 返回 值 未 知 . 


(function(): number) 轰 数 返回 一 个 整数 . 


(function(this:goog.ui.Menu, string)) 函数 
只 带 一 个 参数 (string), 并 且 在 上 下 文 goog.ui.Menu 
中 执行 . 

(function(string, ...[number]): number) fr 
一 个 参数 (字符 类 型 ) 的 函数 类 型 , HE c8 A CAM 
数 可 变 , 但 参数 类 型 必须 为 number. 


@param {...number} var args 函数 参数 个 数 可 
ZR 


X. 


ffunction(?string=, number=)} 函数 带 一 个 可 
空 且 可 选 的 字符 串 型 参数 , 一 个 可 选 整 型 参数 ，= 
语法 只 针对 function 类 型 有 效 . 


Øparam (number-) opt argument number 类 


型 的 可 选 参数 . 


1; 


JavaScript 中 的 类 型 


number 


1 

1.0 

Eum 

1e5 
Math.PI 


Number 


BAB R 


string, 和 un 
不 可 为 空 . 


说 明 一 个 函 
EN då 


HE BARA 
LRA. 


DE dicis s 
数 . 


使 用 标记 , 说 
ARE LSA 


DE dd 6 s 


使 用 标记 , 说 
有 可 选 参数 . 


表示 变量 可 


new Number(true) 


string 


字符 串 值 


' Hello' 
"World" 
String(42) 


String 
FA BE 


new String('Hello') 
new String(42) 


boolean 


布尔 值 


Boolean(0) 


Boolean 
布尔 对 象 

new Boolean(true) 
RegExp 


new RegExp('hello') 
/world/g 


Date 


new Date 
new Date() 


null 


null 


undefined 
undefined 
void 

没有 返回 值 


function f() ( 
return; 


j 


Array 
类 型 不 明确 的 数组 


['foo', 0.3, null] 
[] 


Array .<number> 


[11, 22, 33] 


Array .<Array .<string>> 


Array .<Array.<string>> 


Object 


{} 
(foo: 'abc', bar: 123, baz: null) 


Object.«string» 


{'foo': 'bar'} 


Object.<number, string> 
键 为 整数 , 值 为 字符 串 的 对 象 . 

注意 , JavaScript 中 , 键 总 是 被 转换 成 字符 串 ,所 以 obj['1'] == obj[1] .也 所 以 ， 
键 在 for...in 循环 中 是 字符 串 类 型 . 但 在 编译 器 中 会 明确 根据 键 的 类 型 来 查找 对 象 . 


var obj = {}; 
obj[1] = 'bar'; 
Function 


RRIA 


function(x, y) { 
return x * y; 


} 


function(number, number): number 


函数 值 


function(x, y) { 
return x * y; 


} 


SomeClass 


/** @constructor */ 
function SomeClass() {} 


new SomeClass(); 


SomeInterface 


/** Øinterface */ 
function SomeInterface() (3 


SomeInterface.prototype.draw = function() {}; 


project.MyClass 


/** @constructor */ 
project.MyClass = function () {} 


new project.MyClass() 


project.MyEnum 


枚 举 


/** Qenum (string) */ 

project.MyEnum - ( 
BLUE: '#0000dd', 
RED: '#dd0000' 


3 
Element 
DOM 中 的 元 素 
document.createElement('div') 
Node 
DOM 中 的 节点 . 
document .body.firstChild 
HTMLInputElement 
DOM 中 , 特定 类 型 的 元 素 . 


htmlDocument.getElementsByTagName( 'input')[0] 


可 空 ws. Tit 参数 和 属性 


JavaScript 是 一 种 弱 类 型 语言 , 明白 可 选 , 非 空 和 未 定义 参数 或 属性 之 间 的 细微 差别 
还 是 很 重要 的 . 


对 象 类 型 (引用 类 型 ) 默 认 非 空 . 注意 : 函数 类 型 默认 不 能 为 空 . 


除了 字符 串 , 整 型 , 布尔 , undefined 和 null 外 , 对 象 可 以 是 任何 类 型 . 


Fe 
* Some class, initialized with a value. 
* @param (Object) value Some value. 
* @constructor 
fs 
function MyClass(value) { 
AXES 
* Some value. 
* @type {Object} 
* @private 
qud 
this.myValue = value; 


} 


告诉 编译 器 myvalue ”属性 为 一 对 象 或 null. 如 果 myvalue 永远 都 不 会 为 null， 
就 应 该 如 下 声明 : 


JESS 
* Some class, initialized with a non-null value. 
* param {!Object} value Some value. 
* @constructor 
Pu 
function MyClass(value) ( 
Yrs 
* Some value. 
* @type {!Object} 
* @private 
ey 
this.myValue = value; 


} 


SE, 当 编 译 器 在 代码 中 碰 到 MyClass A null 时 , 就 会 给 出 警告 . 


函数 的 可 选 参 数 可 能 在 运行 时 没有 定义 , 所 以 如 果 他 们 又 被 赋 给 类 属性 , 需要 声明 成 : 


Jf sa 
* Some class, initialized with an optional value. 
* param (Object=) opt value Some value (optional). 
* @constructor 
sy 
function MyClass(opt_value) { 
RSS 
* Some value. 
* @type {Object | undefined} 
* @private 
i 
this.myValue = opt value; 


j 


这 告诉 编译 器 myvalue 可 能 是 一 个 对 象 , 或 null, & undefined. 


ÆR: THER opt value 被 声明 成 (Object=) ,而 不 是 
{0bject|undefined} . 这 是 因为 可 选 参数 可 能 是 undefined. 虽然 直接 写 
undefined 也 并 无 害处 ,但 鉴于 可 阅读 性 还 是 写成 上 述 的 样子 . 


最 后 , 属性 的 非 空 和 可 选 并 不 矛盾 , 属性 既 可 是 非 空 , 也 可 是 可 选 的 .下面 的 四 种 声明 
各 不 相同 : 


* 
* Takes four arguments, two of which are nullable, and two of whi« 
* optional. 

* param {!Object} nonNull Mandatory (must not be undefined), musi 
* param (Object) mayBeNull Mandatory (must not be undefined), may 
* param {!Object=} opt nonNull Optional (may be undefined), but : 
s must not be null! 

* param (Object=) opt mayBeNull Optional (may be undefined), may 


function strangeButTrue(nonNull, mayBeNull, opt nonNull, opt mayBe! 
C Ee 
i 


E — 





注释 
使 用 JSDoc 


我 们 使 用 JSDoc 中 的 注释 风格 . 行内 注释 使 用 // 变量 的 形式 . 另外 , 我 们 也 遵循 C++ 
代码 注释 风格 . 这 也 就 是 说 你 需要 : 


e 版 权 和 著作 权 的 信息 ， 

e 文件 注释 中 应 该 写 明 该 文件 的 基本 信息 (如 , 这 段 代码 的 功能 摘要 , 如 何 使 用 , 与 
哪些 东西 相 X) 来 告诉 那些 不 熟悉 代码 的 读者 . 

e Å, B 变 2 

e AR de i 

e Feo dun 写 , 标点 和 拼 


为 了 避免 出 现 句 子 片 段 , 请 以 合适 的 大 /小 写 单词 开头 , 并 以 合适 的 标点 符号 结束 这 个 
IF. 


现在 假设 维护 这 段 代码 的 是 一 位 初学 者 . 这 可 能 正好 是 这 样 的 ! 
目前 很 多 编译 器 可 从 JSDoc 中 提取 类 型 信息 , 来 对 代码 进行 验证 , 删除 和 压缩 . 
此 , 你 很 有 必要 去 熟悉 正确 完整 的 JSDoc . 
RISE EAE 
顶层 注释 用 于 告诉 不 熟悉 这 段 代码 的 读者 这 个 文件 中 包含 哪些 东西 . 
应 该 提供 文件 的 大 体内 容 , 它 的 作者 , 依赖 关系 和 兼容 性 信息 . 如 下 : 


// Copyright 2009 Google Inc. All Rights Reserved. 

EUN 
* Qfileoverview Description of file, its uses and information 
* about its dependencies. 


* @author user@google.com (Firstname Lastname) 
7 


每 个 类 的 定义 都 要 附带 一 份 注释 , 描述 类 的 功能 和 用 法 .也 需要 说 明 构造 器 参数 ， 


如 果 该 类 继承 自 其 它 类 , 应 该 使 用 @extends 标记 . 


如 果 该 类 是 对 接口 的 实现 , 应 该 使 用 @implements 标记 . 


VASE 
* Class making something fun and easy. 
* param {string} argi An argument that makes this more interestir 
* @param (Array.<number>) arg2 List of numbers to be processed. 
* @constructor 
* Qextends {goog.Disposable} 
S 
project.MyClass = function(argi, arg2) { 
A/ 
J; 


goog.inherits(project.MyClass, goog.Disposable); 


«| mE 











方法 与 函数 的 注释 
提供 参数 的 说 明 . 使 用 完整 的 句子 , 并 用 第 三 人 称 来 书写 方法 说 明 ， 


VERUS 
* Converts text to some completely different text. 
* param {string} argi An argument that makes this more interestir 
* Qreturn (string) Some return value. 
A 
project.MyClass.prototype.someMethod = function(argi) { 
qup 


c 


ffs 
* Operates on an instance of MyClass and returns something. 
* @param {project.MyClass} obj Instance of MyClass which leads to 


å comment that needs to be wrapped to two lines. 
* Qreturn (boolean) Whether something occured. 
ay 
function PR_someMethod(obj) { 
// 





对 于 一 些 简单 的 , 不 带 参 数 的 getters, 说 明 可 以 忽略 . 


jf sia 
* @return {Element} The element for the component. 
ay, 

goog.ui.Component.prototype.getElement = function() { 
return this.element_; 


>; 


属性 注释 


需要 对 属性 进行 注释 . 


Jf is 
* Maximum number of things per pane. 
* Qtype (number) 
gU 


project.MyClass.prototype.someProperty - 4; 


类 型 转换 的 注释 


有 时 , 类 型 检查 不 能 很 准确 地 推断 出 表达 式 的 类 型 , 所 以 应 该 给 它 添加 类 型 标记 注释 
来 明确 之 , 并 且 必 须 在 表达 式 和 类 型 标签 外 面包 衰 括号 . 


/** Qtype (number) */ (x) 
(/** Qtype (number) */ x) 


JSDoc å 3t 


is 
A. 


如 果 你 在 @param , @return , @supported , Qt 


his 或 Qdeprecated PPT 
行 , 需要 像 在 代码 中 一 样 ,使 用 4 个 空格 作为 一 个 缩 进 层 


* 

* Illustrates line wrapping for long param/return descriptions. 

* @param (string) foo This is a param with a description too long 
z one line. 

* @return {number} This returns something that has a description i 
3 fit in one line. 


S 

project.MyClass.prototype.method = function(foo) { 
return 5; 

J; 


EJE) 





FEE Qfileoverview 标记 中 进行 缩 进 . 


虽然 不 建议 , 但 也 可 对 说 明文 字 进 行 适当 的 排版 对 齐 . 不 过 , 这 样 带 来 一 些 负面 影响 ， 
就 是 当 你 每 次 修改 变量 名 时 , 都 得 重新 排版 说 明文 字 以 保持 和 变量 名 对 齐 . 








VASE 
* This is NOT the preferred indentation method. 
* @param (string) foo This is a param with a description too long 
5 one line. 
* @return {number} This returns something that has a description i 
i fit in one line. 
S 
project.MyClass.prototype.method = function(foo) { 
return 5; 
}; 
«| m 
枚 举 
VASES 


* Enum for tri-state values. 
* @enum (number) 
wh 
project.TriState = { 
TRUE: 1, 
FALSE: -1, 
MAYBE: 0 


Hh 


注意 一 下 , 枚 举 也 具有 有 效 类 型 , 所 以 可 以 当成 参数 类 型 来 用 . 


RSEN 
* Sets project state. 
* param {project.TriState} state New project state. 
ur 
project.setState = function(state) { 
// 


>; 


Typedefs 


有 时 类 型 会 很 复杂 . 比如 下 面 的 函数 , 接收 Element 参数 : 


JS 
* @param {string} tagName 
* @param {(string|Element|Text|Array.<Element>|Array.<Text>)} coni 
* @return {Element} 
Sy 
goog.createElement = function(tagName, contents) { 


7 


«| E 








你 可 以 使 用 Qtypedef 标记 来 定义 个 常用 的 类 型 表达 式 . 


Iss 

* @param {string} tagName 

* @param {goog.ElementContent} contents 

* @return {Element} 

a 

goog.createElement = function(tagName, contents) { 


EE 
JSDoc 标记 表 


@param 


模板 & 例子 : 


@param {Type} 变量 名 描述 


如 : 


Pi 

* Queries a Baz for items. 

* @param (number) groupNum Subgroup id to query. 

* @param {string|number|null} term An itemName, 

S or itemId, or null to search everything. 

AA 

goog.Baz.prototype.query = function(groupNum, term) { 
VETE 


>; 


描述 : 给 方法 , 函数 , 构造 器 中 的 参数 添加 说 明 . 


类 型 检测 支持 : 完全 支持 . 


Qreturn 


模板 & 例子 : 


Qreturn (Type) 描述 


he: 


PATER 

* Qreturn (string) The hex ID of the last item. 
Ya 

goog.Baz.prototype.getLastId = function() { 
EEE 


return id; 
jg 
描述 : 给 方法 , 函数 的 返回 值 添加 说 明 . 在 描述 布尔 型 参数 时 ， 


Å “Whether the component is visible” 这 种 描述 优 于 “True if the component is 
visible, false otherwise". 


函数 没有 返回 值 , 就 不 需要 添加 Qreturn 标记 . 
类 型 检测 支持 : 完全 支持 . 
Qauthor 


模板 & 例子 : 


Qauthor usernameQgoogle.com (first last) 


he: 


JE 

* Qfileoverview Utilities for handling textareas. 

* @author kuth@google.com (Uthur Pendragon) 

ra 
描述 : 表明 文件 的 作者 ,通常 仅 会 在 Qfileoverview 注释 中 使 用 到 它 . 
类 型 检测 支持 : 不 需要 . 


Qsee 


模板 & 例子 : 


Qsee Link 


如 : 


VÆSKE 

* Adds a single item, recklessly. 
* @see #addSafely 

* @see goog.Collect 

* @see goog.RecklessAdder#add 


描述 : 给 出 引用 链接 , 用 于 进一步 查看 函数 /方法 的 相关 细节 . 
类 型 检测 支持 : TER. 


Qfileoverview 


模板 & 例子 : 


Qfileoverview 描述 


he: 


ae 

* @fileoverview Utilities for doing things that require this very - 
* but not indented comment. 

* @author kuth@google.com (Uthur Pendragon) 





描述 : 文件 通 览 . 
类 型 检测 支持 : 不 需要 


Qconstructor 


模板 & 例子 : 


Øconstructor 


he: 


JA 

* A rectangle. 

* (constructor 

Å 

function GM Rect() I 


a 


描述 : 指明 类 中 的 构造 器 . 
类 型 检测 支持 : 会 检查 . 如 果 省 略 了 , 编译 器 将 禁止 实例 化 . 


Qinterface 


模板 & 例子 


Qinterface 


如 : 


YE 

* A shape. 

* @interface 

rå 

function Shape() {}; 

Shape .prototype.draw = function() {}; 


HES 

* A polygon. 

* @interface 

* @extends {Shape} 

(d 

function Polygon() {}; 
Polygon.prototype.getSides = function() {}; 


描述 : 指明 这 个 函数 是 一 个 接口 . 


类 型 检测 支持 : 会 检查 . 如 果实 例 化 一 个 接口 ,编译 器 会 警告 


@type 
模板 & 例子 : 


Qtype Type 
Qtype (Type) 


he: 


ff visa 

* The message hex ID. 
* @type {string} 

2 


var hexId = hexId; 


描述 : 标识 变量 , 属性 或 表达 式 的 类 型 . 
大 多 数 类 型 是 不 需要 加 大 括号 的 , 但 为 了 保持 一 致 , 建议 统一 加 大 括号 .| 
类 型 检测 支持 SHEA 


Qextends 


模板 & 例子 : 


Qextends Type 
Qextends {Type} 


he: 


Vas 

* Immutable empty node list. 

* @constructor 

* @extends goog.ds.BasicNodeList 

=y 

goog.ds.EmptyNodeList = function() { 


y 


描述 : 与 @constructor 一 起 使 用 , 用 来 表明 该 类 是 扩展 自 其 它 类 的 . 类 型 外 的 大 括 
335745. 


类 型 检测 支持 : 会 检查 
Qimplements 


模板 & 例子 : 


Qimplements Type 
@implements {Type} 


如 : 


VASE 

* A shape. 

* @interface 

*/ 

function Shape() {}; 
Shape.prototype.draw = function() {}; 


JS 

* @constructor 

* @implements {Shape} 

as 

function Square() {}; 
Square.prototype.draw = function() { 


T 
描述 : 与 @constructor 一 起 使 用 , 用 来 表明 该 类 实现 自 一 个 接口 . 类 型 外 的 大 括号 


可 写 可 不 写 . 
类 型 检测 支持 : 会 检查 . 如 果 接 口 不 完整 , 编译 器 会 警告 . 


@lends 


模板 & 例子 : 


Qlends objectName 
Qlends {objectName} 


he: 


goog.object.extend( 

Button.prototype, 

/** @lends {Button.prototype} */ ( 
isButton: function() { return true; } 


3); 


描述 : 表示 把 对 象 的 键 看 成 是 其 他 对 象 的 属性 . 该 标记 只 能 出 现在 对 象 语法 中 . 


注意 , 括号 中 的 名 称 和 其 他 标记 中 的 类 型 名 称 不 一 样 , 它 是 一 个 对 象 名 , 以 " 借 过 来 "的 
属性 名 命名 . 


如 , @type (Foo) Å TF “Foo 的 一 个 实例 ”but lends {Foo} 表示 “Foo 构造 器 ” 
更 多 有 关 此 标记 的 内 容 见 JSDoc Toolkit docs. 
类 型 检测 支持 : 会 检查 


Qprivate 


模板 & 例子 : 


Qprivate 


如 : 


Ws 

* Handlers that are listening to this logger. 
* Qtype Array.<Function> 

* @private 

d 

this.handlers = []; 


描述 : 指明 那些 以 下 划 线 结尾 的 方法 和 属性 是 
私有 的 . 


不 推荐 使 用 后 组 下 划 线 , 而 应 改 用 @private 
类 型 检测 支持 : 需要 指定 标志 来 开启 . 


@protected 


模板 & 例子 : 


@protected 


dv: 


Ves 

* Sets the component's root element to the given element.  Considei 
* protected and final. 

* param (Element) element Root element for the component. 

* Qprotected 

s 

goog.ui.Component.prototype.setElementInternal = function(element) 
OA 


HH 





描述 : 指明 接 下 来 的 方法 和 属性 是 被 保护 的 . 
被 保护 的 方法 和 属性 的 命名 不 需要 以 下 划 线 结尾 , 和 普通 变量 名 没 


ba 
Ns 


|. | 


类 型 检测 支持 : 需要 指定 标志 来 开局. 
Qthis 


模板 & 例子 : 


Qthis Type 
Qthis (Type) 


he: 


pinto.chat.RosterWidget.extern('getRosterElement', 
VASE 

* Returns the roster widget element. 

* Qthis pinto.chat.RosterWidget 

* Øreturn (Element) 

A 

function() { 

return this.getWrappedComponent ().getElement(); 
3); 


描述 : 指明 调用 这 个 方法 时 , 需要 在 哪个 上 下 文中 . 2 this 48 6 49 TÆR Zr TAL AN SH 
数 时 必须 使 用 这 个 标记 . 
类 型 检测 支持 : 会 检查 


@supported 


模板 & 例子 : 


Qsupported 描述 


he: 


Yee 

* @fileoverview Event Manager 

* Provides an abstracted interface to the 

* browsers' event systems. 

* @supported So far tested in IE6 and FF1.5 
2 


描述 : 在 文件 概述 中 用 到 , 表明 支持 哪些 浏览 器 . 
类 型 检测 支持 : 不 需要 . 


Qenum 


模板 & 例子 : 


@enum {Type} 


如 : 


AREA 

* Enum for tri-state values. 
* @enum (number) 

“y 

project.TriState = { 

TRUE: 1, 

FALSE: -1, 

MAYBE: O 

}; 


描述 : 用 于 枚 举 类 型 . 


类 型 检测 支持 : 完全 支持 . 如 果 省 略 , 会 认为 是 整 型 . 


@deprecated 


模板 & 例子 : 


@deprecated 描述 


he: 


aka 


* Determines whether a node is a field. 
* @return {boolean} True if the contents of 


i: the element are editable, 


å itself is not. 

* @deprecated Use isField(). 
2 

BN EditUtil.isTopEditableField 
NES. 

3 


描述 : 告诉 其 他 开发 人 员 , 此 方法 , 函数 已 


法 或 函数 . 
类 型 检测 支持 : 不 需要 


but the element 


= function(node) { 


经 过 时 , 不 要 再 使 用 . 同时 也 会 给 出 替代 方 


Qoverride 


模板 & 例子 : 


Qoverride 


he: 


EEE 

* Qreturn (string) Human-readable representation of project.SubCla: 
* Qoverride 

ay 

project.SubClass.prototype.toString() { 

OA 


3 
Ki = 5 


描述 : 指明 子 类 的 方法 和 属性 是 故意 隐藏 了 父 类 的 方法 和 属性 . 如 果子 类 的 方法 和 
属性 没有 自己 的 文档 , 就 会 继承 父 类 的 . 


类 型 检测 支持 : 会 检查 





@inheritDoc 


模板 & 例子 : 


ØinheritDoc 


he: 


/** @inheritDoc */ 
project.SubClass.prototype.toString() { 
1 e 


>; 


描述 : 指明 子 类 的 方法 和 属性 是 故意 隐藏 了 父 类 的 方法 和 属性 , 它们 具有 相同 的 文 
档 . 注意 : 使 用 @inheritDoc 意味 着 也 同时 使 用 了 @override. | 

类 型 检测 支持 : 会 检查 

Qcode 


模板 & 例子 : 


{@code ..) 


he: 


VASES 

* Moves to the next position in the selection. 

* Throws {@code goog.iter.StopIteration) when it 

* passes the end of the range. 

* Qreturn (Node) The node at the next position. 

=y 

goog.dom.Rangelterator.prototype.next = function() { 
EE 

3 


描述 : 说 明 这 是 一 段 代码 , 让 它 能 在 生成 的 文档 中 正确 的 格式 化 . 
类 型 检测 支持 : 不 适用 


@license Or (preserve 


模板 & 例子 


Qlicense 


描述 : 


he: 


ake 

* @preserve Copyright 2009 SomeThirdParty. 

* Here is the full license text and copyright 

* notice for this file. Note that the notice can span several 
* lines and is only terminated by the closing star and slash: 


s 


描述 : 所 有 被 标记 为 @license 或 (preserve 的 , 会 被 编译 器 保留 不 做 任何 修改 而 
直接 输出 到 最 终 文 挡 中 . 


这 个 标记 让 一 些 重 要 的 信息 (如 法 律 许 可 或 版 权 信 息 ) 原 样 保 留 , 同样 , 文本 中 的 换行 
也 会 被 保留 . | 


类 型 检测 支持 : 不 需要 . 


Qnoalias 


模板 & 例子 : 


Ønoalias 


he: 


/** @noalias */ 
function Range() {} 


描述 : 在 外 部 文件 中 使 用 , 告诉 编译 器 不 要 为 这 个 变量 或 函数 重 命名 . 
类 型 检测 支持 : 不 需要 . 
Qdefine 


模板 & 例子 : 


Qdefine (Type) 描述 


如 : 


/** @define {boolean} */ 
var TR FLAGS ENABLE DEBUG = true; 


/** @define (boolean) */ 
goog.userAgent.ASSUME IE = false; 


描述 : 表示 该 变量 可 在 编译 时 被 编译 器 重新 赋值 
在 上 面 例子 中 , BUILD 文件 中 指定 了 
-define-'goog.userAgent.ASSUME IE-true' 
这 个 编译 之 后 , 常量 goog.userAgent. ASSUME IE 将 被 全 部 直接 替换 为 true. 
类 型 检测 支持 : 不 需要 . 
Qexport 


模板 & 例子 : 


Qexport 


he: 


/** @export */ 
foo.MyPublicClass.prototype.myPublicMethod = function() { 
FAEN 


}; 
描述 : 


上 面 的 例子 代码 , 当 编 译 器 运行 时 指定 —generate_exports 标志 , 会 生成 下 面 的 代码 : 


goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', 
foo.MyPublicClass.prototype.myPublicMethod); 


编译 后 , 将 源 代码 中 的 名 字 原 样 导 出 . 
使 用 @export 标记 时 , 应 该 
1. 包含 //javascript/closure/base.js, 或 者 
2. 在 代码 库 中 自 定义 goog.exportSymbol 和 goog.exportProperty 两 个 方法 , 并 保 
证 有 相同 的 调用 方式 . 


类 型 检测 支持 : 不 需要 . 
Qconst 


模板 & 例子 : 


Øconst 


he: 


/** @const */ var MY BEER = 'stout'; 
USES 
* My namespace's favorite kind of beer. 


* Øconst 
* Qtype (string) 
SA 


mynamespace.MY BEER - 'stout'; 


/** @const */ MyClass.MY BEER = 'stout'; 


描述 : 


声明 变量 为 只 读 , 直接 写 在 一 行 上 . 


如 果 其 他 代码 中 重 写 该 变量 值 , 编译 器 会 警告 . 

常量 应 全 部 用 大 写字 符 , 不 过 使 用 这 个 标记 , 可 以 帮 你 消除 命名 上 依赖 . 
虽然 jsdoc.org 上 列 出 的 @final 标记 作用 等 价 于 @const , 但 不 建议 使 用 . 
@const 与 JS1.5 中 的 const 关键 字 一 致 . 

注意 , 编译 器 不 禁止 修改 常量 对 象 的 属性 (这 与 C++ 中 的 常量 定义 不 一 样 ). 


如 果 可 以 准确 推测 出 常量 类 型 的 话 ， 那 么 类 型 申明 可 以 忽略 . 如 果 指 定 了 类 型 , 应 该 
也 写 在 同一 行 上 . 


变量 的 额外 注释 可 写 可 不 写 
类 型 检测 支持 : 支持 . 


@nosideeffects 


模板 & 例子 : 


Qnosideeffects 


he: 


/** @nosideeffects */ 
function noSideEffectsFn1() I 
JANE 


HH 


/** Ønosideeffects */ 
var noSideEffectsFn2 = function() { 
AT 


jee 
/xx @nosideeffects */ 


a.prototype.noSideEffectsFn3 = function() I 
V ase 


描述 : Tou BARWBS PA, 说 明 调用 此 函数 不 会 有 副 作用 . 编译 器 遇 到 此 标记 
时 , 如 果 调 用 函数 的 返回 值 没有 其 他 地 方 使 用 到 , 则 会 将 这 个 函数 整个 删除 . 

类 型 检测 支持 : 不 需要 检查 . 

Qtypedef 

模板 & 例子 


Qtypedef 


he: 


/** @typedef {(string|number)} */ 
goog.NumberLike; 


/** @param {goog.NumberLike} x A number or a string. */ 
goog.readNumber = function(x) { 


n 


描述 : 这 个 标记 用 于 给 一 个 复杂 的 类 型 取 一 个 别名 . 


类 型 检测 支持 : 会 检查 
Qexterns 


模板 & 例子 : 


Qexterns 


如 : 


Jf ets 

* Qfileoverview This is an externs file. 
* @externs 

aye 


var document; 


描述 : 
间 明 一 个 外 部 文件 . 
类 型 检测 支持 : 不 会 检查 


在 第 三 方 代码 中 , 你 还 会 见 到 其 他 一 些 JSDoc 标记 . 这 些 标记 在 JSDoc Toolkit Tag 
Reference 都 有 介绍 到 , 但 在 Google 的 代码 中 , 目前 不 推荐 使 用 . 你 可 以 认为 这 些 是 
将 来 会 用 到 的 “保留 " 名 . 它们 包含 : 


@augments 
@argument 
@borrows 
@class 
@constant 


(constructs 
(Qdefault 
(Qevent 
@example 
@field 
@function 
@ignore 
@inner 
@link 
@memberOf 
@name 
@namespace 
@property 
@public 
@requires 
@returns 
@since 
@static 
@version 


JSDoc 中 的 HTML 


X4 T JavaDoc, JSDoc 支持 许多 HTML 标签 , 如 <code> , <pre> , 


<strong> , <ul> , <ol>, <li>, <a> , 4. 


这 就 是 说 JSDoc 不 会 完全 依照 纯 文 本 中 书写 的 格式 . 所 以 , 不 要 在 JSDoc F, 使 用 
空白 字符 来 做 格式 化 : 


ffs 
* Computes weight based on three factors: 
s items sent 
i items received 
i last timestamp 
n 


上 面 的 注释 , 出 来 的 结果 是 : 


Computes weight based on three factors: items sent items received : 


P 






VASE 
* Computes weight based on three factors: 
* «ul» 
* <li>items sent 
* <li>items received 
* <li>last timestamp 
* «/ul» 


另外 , 也 不 要 包含 任何 HTML 或 类 HTML 标签 , 除非 你 就 想 让 它们 解析 成 HTML 标 


会 


J 
* Changes <b> tags to tags. 
a7 


出 来 的 结果 是 : 


Changes tags to tags. 


另外 , 也 应 该 在 源 代码 文件 中 让 其 他 人 更 可 读 , 所 以 不 要 过 于 使 用 HTML 标签 : 


A 
* Changes &lt;b&gt; tags to &lt;span&gt; tags. 
ud 


上 面 的 代码 中 , 其 他 人 就 很 难 知道 你 想 干 嘛 , 直接 改 成 下 面 的 样子 就 清楚 多 了 : 


VER 
* Changes 'b' tags to 'span' tags. 
id 
编译 
推荐 使 用 
建议 您 去 使 用 JS 编译 器 , 如 Closure Compiler. 
Tips and Tricks 
JavaScript 小 技巧 
True 和 False 布尔 表达 式 


下 面 的 布尔 表达 式 都 返回 false: 


null 
undefined 
v 空 字符 囊 
o 数字 0 


但 小 心 下 面 的 , 可 都 返回 true: 


e '0' 字符 串 0 
e [] 空 数组 
。 {} 空 对 象 


下 面 段 比较 糟糕 的 代码 : 

while (x != null) { 

你 可 以 直接 写成 下 面 的 形式 (只 要 你 希望 X 不 是 0 和 空 字 符 串 , 和 false): 
如 果 你 想 检 查 字 符 串 是 否 为 null SE 


if (y != null && y != '') I 


注意 : 还 有 很 多 需要 注意 的 地 方 , 如 : 
e Boolean('0') == true '0' !- true 


e 0 != null © == [] 0 == false 


e Boolean(null) == false null != true null != false 

e Boolean(undefined) == false undefined != true 
undefined != false 

e Boolean([]) == true [] != true [] == false 


e Boolean({}) == true {} != true {} != false 


条 件 ( 三 元 ) 操 作 符 (3:) 
三 元 操作 符 用 于 替代 下 面 的 代码 : 


if (val != 0) ( 
return foo(); 
) else I 
return bar(); 


) 


你 可 以 写成 : 
在 生成 HTML 代码 时 也 是 很 有 用 的 : 


var html = '«input type="checkbox"" + 
(isChecked ? ' checked' : '') + 
(isEnabled ? '' : ' disabled') + 


' name="foo0">"; 


&& 和 || 


二 元 布尔 操作 符 是 可 短路 的 , 只 有 在 必要 时 才 会 计算 到 最 后 一 项 . 
“||” 被 称 作 为 ‘default 操作 符 , 因为 可 以 这 样 : 


/** @param {*=} opt win */ 
function foo(opt win) { 
var win; 
if (opt win) ( 
win - opt win; 
) else { 
win = window; 
) 
OA 


j 


你 可 以 使 用 它 来 简化 上 面 的 代码 : 


/** @param {*=} opt win */ 
function foo(opt win) { 
var win - opt win || window; 
dea. 
j 


“&&” 也 可 简短 代码 .比如 : 


if (node) { 
if (node.kids) ( 
if (node.kids[index]) (1 
foo(node.kids[index]); 


} 
} 
} 


你 可 以 像 这 样 来 使 用 : 
if (node && node.kids && node.kids[index]) I 


foo(node.kids[index]); 


j 


或 者 : 
var kid = node && node.kids && node.kids[index]; 


if (kid) I 
foo(kid); 
) 


不 过 这 样 就 有 点 儿 过 头 了 : 


node && node.kids && node.kids[index] && foo(node.kids[index]); 


使 用 join() 来 创建 字符 串 
通常 是 这 样 使 用 的 : 
function listHtml(items) ( 


var html = ''; 
for (var i 


; i < items.length; ++i) { 
html += itemHtml(items[i]); 

} 

html += ''; 


return html; 


} 


但 这 样 在 IE 下 非常 慢 , 可 以 用 下 面 的 方式 : 


function listHtml(items) ( 
var html - []; 
for (var i = 0; i < items.length; ++i) I 
html[i] = itemHtml(items[i]); 


return '' + html.join(', ') + ''; 


} , 


你 也 可 以 是 用 数组 作为 字符 串 构造 器 , 然后 通过 myArray.join('') 转换 成 字符 
P. 不 过 由 于 赋值 操作 快 于 数组 的 push() ,所 以 尽量 使 用 赋值 操作 . 


遍历 Node List 

Node lists 是 通过 给 节点 迭代 器 加 一 个 过 滤器 来 实现 的 . 
这 表示 获取 他 的 属性 , 如 length 的 时 间 复 杂 度 为 O(n), 通过 length 来 遍历 整个 列表 
需要 O(n^2). 


var paragraphs = document.getElementsByTagName( 'p'); 

for (var i = 0; i < paragraphs.length; i++) { 
doSomething(paragraphs[i]); 

) 


这 样 做 会 更 好 : 
var paragraphs = document.getElementsByTagName( 'p'); 
for (var i = 0, paragraph; paragraph = paragraphs[i]; i++) { 


doSomething(paragraph); 
) 


这 种 方法 对 所 有 的 collections 和 数组 (只 要 数组 不 包含 falsy få) 都 适用 . 
在 上 面 的 例子 中 , 也 可 以 通过 firstChild 和 nextSibling 来 遍历 孩子 节点 . 


var parentNode = document.getElementById('foo'); 
for (var child = parentNode.firstChild; child; child = child.nexts: 
doSomething(child); 


Hæ eee] 





Parting Words 


保持 一 致 性 . 
当 你 在 编辑 代码 之 前 , 先 花 一 些 时 间 查 看 一 下 现 有 代码 的 风格 , 如 果 他 们 给 算术 运算 
符 添加 了 空格 , 你 也 应 该 添加 . 

如 果 他 们 的 注释 使 用 一 个 个 星 号 盒子 , 那么 也 请 你 使 用 这 种 方式 . 

代码 风格 中 一 个 关键 点 是 整理 一 份 常用 词汇 表 , 开发 者 认同 它 并 且 遵 循 , 这 样 在 代码 
中 就 能 统一 表述 . 

我 们 在 这 提出 了 一 些 全 局 上 的 风格 规则 , 但 也 要 考虑 自身 情况 形成 自己 的 代码 风格 . 
但 如 果 你 添加 的 代码 和 现 有 的 代码 有 很 大 的 区 别 , 这 就 让 阅读 者 感到 很 不 和 谐 . 


所 以 , 避免 这 种 情况 的 发 生 . 


